feat(organizations): create endpoints to handle organization invitations TASK-969 #5395

rajpatel24 · 2024-12-20T15:00:43Z

🗒️ Checklist

run linter locally
update all related docs (API, README, inline, etc.), if any
draft PR with a title <type>(<scope>)<!>: <title> TASK-1234
tag PR: at least frontend or backend unless it's global
fill in the template below and delete template comments
review thyself: read the diff and repro the preview as written
open PR & confirm that CI passes
request reviewers, if needed
delete this section before merging

📣 Summary

Implemented endpoints for organization invitations, allowing organization owners to invite existing users or unregistered users to join their organization. The invitee can either accept or decline the invitation. If the invitee accepts, their assets will be transferred to the organization.

📖 Description

Organization owners can send invitations to users (both registered and unregistered) via email or username.
The invitee can accept or decline the invitation. If accepted, the invitee's assets will be transferred to the organization owner.

POST https://[kpi]/api/v2/organizations/org_12345/invites/

Create organization invites for registered and unregistered users.
Set the role for which the user is being invited - (Choices: member, admin). Default is member.

Payload:

{
    "invitees": ["demo14", "[email protected]", "[email protected]"],
    "role": "admin"
}

Response:

[
    {
        "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/",
        "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
        "status": "pending",
        "invitee_role": "admin",
        "created": "2025-01-06T13:01:40Z",
        "modified": "2025-01-06T13:01:40Z",
        "invitee": "demo14"
    },
    {
        "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/6746121a-7a87-4c2d-9994-85e38d8cff65/",
        "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
        "status": "pending",
        "invitee_role": "admin",
        "created": "2025-01-06T13:01:40Z",
        "modified": "2025-01-06T13:01:40Z",
        "invitee": "demo13"
    },
    {
        "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/2af706a9-4f67-4145-a0d3-8d66fbc77a19/",
        "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
        "status": "pending",
        "invitee_role": "admin",
        "created": "2025-01-06T13:01:40Z",
        "modified": "2025-01-06T13:01:40Z",
        "invitee": "[email protected]"
    }
]

GET https://[kpi]/api/v2/organizations/org_12345/invites/

Response:

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/6746121a-7a87-4c2d-9994-85e38d8cff65/",
            "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
            "status": "pending",
            "invitee_role": "admin",
            "created": "2025-01-06T13:01:40Z",
            "modified": "2025-01-06T13:01:40Z",
            "invitee": "demo13"
        },
        {
            "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/",
            "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
            "status": "pending",
            "invitee_role": "admin",
            "created": "2025-01-06T13:01:40Z",
            "modified": "2025-01-06T13:01:40Z",
            "invitee": "demo14"
        },
        {
            "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/2af706a9-4f67-4145-a0d3-8d66fbc77a19/",
            "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
            "status": "pending",
            "invitee_role": "admin",
            "created": "2025-01-06T13:01:40Z",
            "modified": "2025-01-06T13:01:40Z",
            "invitee": "[email protected]"
        }
    ]
}

PATCH https://[kpi]/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/

Update an organization invite to accept, decline, cancel, expire, or resend.

Payload:

{
    "status": "accepted"
}

Response:

{
    "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/",
    "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
    "status": "accepted",
    "invitee_role": "admin",
    "created": "2025-01-06T13:01:40Z",
    "modified": "2025-01-06T13:01:40Z",
    "invitee": "demo14"
}

DELETE https://[kpi]/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/

Organization owner or admin can delete an organization invite.

Response: 204

notion-workspace · 2024-12-31T20:36:14Z

Create endpoints to handle org invitations

notion-workspace · 2024-12-31T20:37:06Z

Invitation response validation

notion-workspace · 2024-12-31T20:37:20Z

Invitation e-mail templates

magicznyleszek · 2025-01-04T10:45:17Z

@rajpatel24 Wuld that whole invite object be present in /api/v2/organizations/:organization_id/members/ in the invite property? And I see you have pending status in there, and is this the same as sent?

kobo/apps/organizations/models.py

…tations

rajpatel24 · 2025-01-06T06:20:07Z

@rajpatel24 Wuld that whole invite object be present in /api/v2/organizations/:organization_id/members/ in the invite property? And I see you have pending status in there, and is this the same as sent?

@magicznyleszek No, the invite object would not be present there. I don't think it's necessary since /api/v2/organizations/:organization_id/members/ is designed to list the members who are already part of the organization - those who have accepted the invitations and are now part of it.

The pending status is the same as sent. When the organization owner sends an invitation, the status of the invite will be set to pending.

…tations

kobo/apps/organizations/serializers.py

kobo/apps/organizations/tasks.py

kobo/apps/organizations/models.py

noliveleger · 2025-01-15T22:04:52Z

kobo/apps/organizations/templates/emails/accepted_invite.txt

+
+{% trans "All projects, submissions, data storage, transcription and translation usage for their projects will be transferred to you." %}
+
+{% trans "Note: You will continue to have permissions to manage these projects until the user permissions are changed." %}


I don't think this sentence should be here since that's the sender who receives this message.
(Please fix HTML template too)

kobo/apps/organizations/templates/emails/registered_user_invite.txt

…atuses from the model

kobo/apps/organizations/constants.py

kobo/apps/organizations/models.py

kobo/apps/organizations/permissions.py

kobo/apps/organizations/tasks.py

kobo/apps/organizations/tests/test_organization_invitations.py

kobo/apps/organizations/views.py

noliveleger · 2025-01-23T10:44:42Z

kobo/apps/organizations/models.py

@@ -365,21 +376,26 @@ def send_invite_email(self):
        email_message = EmailMessage(
            to=to_email,
            subject=t(
-                f"You're invited to join {organization_name}'s organization"
-            ),
+                f"You're invited to join ##organization_name## organization"


Does not need to be an f-string anymore

kobo/apps/organizations/models.py

noliveleger · 2025-01-23T11:03:07Z

kobo/apps/organizations/models.py

-                f"You're invited to join {organization_name}'s organization"
-            ),
+                f"You're invited to join ##organization_name## organization"
+            ).replace('##organization_name##', organization_name),


You could use your utility replace_placeholders()

Done. Also I have moved the utility function to a new file, as it is a generic utility not specific to the organizations app.

kobo/apps/organizations/serializers.py

kobo/apps/organizations/tests/test_organization_invitations.py

… refine permissions

… github.com:kobotoolbox/kpi into task-969-create-endpoints-to-handle-org-invitations

noliveleger

LGTM

…ons TASK-969 (#5395) ### 📣 Summary Implemented endpoints for organization invitations, allowing organization owners to invite existing users or unregistered users to join their organization. The invitee can either accept or decline the invitation. If the invitee accepts, their assets will be transferred to the organization. ### 📖 Description - Organization owners can send invitations to users (both registered and unregistered) via email or username. - The invitee can accept or decline the invitation. If accepted, the invitee's assets will be transferred to the organization owner. > POST https://[kpi]/api/v2/organizations/org_12345/invites/ - Create organization invites for registered and unregistered users. - Set the role for which the user is being invited - (Choices: `member`, `admin`). Default is `member`. Payload: ``` { "invitees": ["demo14", "[email protected]", "[email protected]"], "role": "admin" } ``` Response: ``` [ { "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/", "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/", "status": "pending", "invitee_role": "admin", "created": "2025-01-06T13:01:40Z", "modified": "2025-01-06T13:01:40Z", "invitee": "demo14" }, { "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/6746121a-7a87-4c2d-9994-85e38d8cff65/", "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/", "status": "pending", "invitee_role": "admin", "created": "2025-01-06T13:01:40Z", "modified": "2025-01-06T13:01:40Z", "invitee": "demo13" }, { "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/2af706a9-4f67-4145-a0d3-8d66fbc77a19/", "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/", "status": "pending", "invitee_role": "admin", "created": "2025-01-06T13:01:40Z", "modified": "2025-01-06T13:01:40Z", "invitee": "[email protected]" } ] ``` > GET https://[kpi]/api/v2/organizations/org_12345/invites/ Response: ``` { "count": 3, "next": null, "previous": null, "results": [ { "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/6746121a-7a87-4c2d-9994-85e38d8cff65/", "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/", "status": "pending", "invitee_role": "admin", "created": "2025-01-06T13:01:40Z", "modified": "2025-01-06T13:01:40Z", "invitee": "demo13" }, { "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/", "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/", "status": "pending", "invitee_role": "admin", "created": "2025-01-06T13:01:40Z", "modified": "2025-01-06T13:01:40Z", "invitee": "demo14" }, { "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/2af706a9-4f67-4145-a0d3-8d66fbc77a19/", "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/", "status": "pending", "invitee_role": "admin", "created": "2025-01-06T13:01:40Z", "modified": "2025-01-06T13:01:40Z", "invitee": "[email protected]" } ] } ``` > PATCH https://[kpi]/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/ - Update an organization invite to accept, decline, cancel, expire, or resend. Payload: ``` { "status": "accepted" } ``` Response: ``` { "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/", "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/", "status": "accepted", "invitee_role": "admin", "created": "2025-01-06T13:01:40Z", "modified": "2025-01-06T13:01:40Z", "invitee": "demo14" } ``` > DELETE https://[kpi]/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/ - Organization owner or admin can delete an organization invite. Response: 204 --------- Co-authored-by: Olivier Leger <[email protected]>

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 092d932 to 64a2b55 Compare December 30, 2024 15:46

rajpatel24 added the Back end label Dec 30, 2024

rajpatel24 changed the title ~~Create endpoints to handle organization invitations~~ feat(organizations): create endpoints to handle organization invitations Dec 30, 2024

rajpatel24 marked this pull request as ready for review December 30, 2024 16:14

rajpatel24 requested review from jnm and noliveleger as code owners December 30, 2024 16:14

rajpatel24 removed the request for review from jnm December 30, 2024 16:14

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 64a2b55 to 1139076 Compare January 1, 2025 15:45

rajpatel24 self-assigned this Jan 1, 2025

Create endpoints to handle organization invitations

c28ad37

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 1139076 to c28ad37 Compare January 2, 2025 14:20

magicznyleszek reviewed Jan 4, 2025

View reviewed changes

kobo/apps/organizations/models.py Show resolved Hide resolved

magicznyleszek mentioned this pull request Jan 4, 2025

feat(invites): query file for handling API TASK-1092 TASK-991 (wrong base branch) #5407

Closed

9 tasks

Merge branch 'main' into task-969-create-endpoints-to-handle-org-invi…

af29b03

…tations

Update organization invitation tests and email templates

ea9a6bd

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 31ac077 to ea9a6bd Compare January 6, 2025 13:15

magicznyleszek mentioned this pull request Jan 7, 2025

feat(invites): query file for handling API TASK-1092 TASK-991 #5409

Merged

Include invite object in the organization members endpoint

5394358

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 32b1431 to 5394358 Compare January 7, 2025 15:37

rajpatel24 and others added 3 commits January 13, 2025 16:43

Add unit test to validate invite object in organization members list

93eb306

Merge branch 'main' into task-969-create-endpoints-to-handle-org-invi…

1674881

…tations

Merge branch 'main' into task-969-create-endpoints-to-handle-org-invi…

ef41645

…tations

noliveleger requested changes Jan 15, 2025

View reviewed changes

Update organization invitation email templates and remove unwanted st…

c230f54

…atuses from the model

noliveleger requested changes Jan 16, 2025

View reviewed changes

Add additional unit tests for validation and update permissions

7da19ae

rajpatel24 requested a review from noliveleger January 20, 2025 12:00

noliveleger reviewed Jan 23, 2025

View reviewed changes

kobo/apps/organizations/models.py Outdated Show resolved Hide resolved

noliveleger reviewed Jan 23, 2025

View reviewed changes

kobo/apps/organizations/models.py Outdated Show resolved Hide resolved

noliveleger requested changes Jan 23, 2025

View reviewed changes

Move replace_placeholder function to new file, update unit tests, and…

b8f2908

… refine permissions

rajpatel24 requested a review from noliveleger January 23, 2025 15:40

noliveleger added 4 commits January 23, 2025 18:32

Merge branch 'task-969-create-endpoints-to-handle-org-invitations' of…

72398a5

… github.com:kobotoolbox/kpi into task-969-create-endpoints-to-handle-org-invitations

Test linter

c087fef

Remove useless call of activate

41a2078

Linting

386b8ea

noliveleger changed the title ~~feat(organizations): create endpoints to handle organization invitations~~ feat(organizations): create endpoints to handle organization invitations TASK-969 Jan 23, 2025

noliveleger approved these changes Jan 23, 2025

View reviewed changes

rajpatel24 merged commit ea727fb into main Jan 24, 2025
4 checks passed

rajpatel24 deleted the task-969-create-endpoints-to-handle-org-invitations branch January 24, 2025 07:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(organizations): create endpoints to handle organization invitations TASK-969 #5395

feat(organizations): create endpoints to handle organization invitations TASK-969 #5395

rajpatel24 commented Dec 20, 2024 •

edited

Loading

notion-workspace bot commented Dec 31, 2024

notion-workspace bot commented Dec 31, 2024

notion-workspace bot commented Dec 31, 2024

magicznyleszek commented Jan 4, 2025 •

edited

Loading

rajpatel24 commented Jan 6, 2025

noliveleger Jan 15, 2025

noliveleger Jan 23, 2025

noliveleger Jan 23, 2025

rajpatel24 Jan 23, 2025

noliveleger left a comment


		{% trans "All projects, submissions, data storage, transcription and translation usage for their projects will be transferred to you." %}

		{% trans "Note: You will continue to have permissions to manage these projects until the user permissions are changed." %}

feat(organizations): create endpoints to handle organization invitations TASK-969 #5395

feat(organizations): create endpoints to handle organization invitations TASK-969 #5395

Conversation

rajpatel24 commented Dec 20, 2024 • edited Loading

🗒️ Checklist

📣 Summary

📖 Description

notion-workspace bot commented Dec 31, 2024

notion-workspace bot commented Dec 31, 2024

notion-workspace bot commented Dec 31, 2024

magicznyleszek commented Jan 4, 2025 • edited Loading

rajpatel24 commented Jan 6, 2025

noliveleger Jan 15, 2025

Choose a reason for hiding this comment

noliveleger Jan 23, 2025

Choose a reason for hiding this comment

noliveleger Jan 23, 2025

Choose a reason for hiding this comment

rajpatel24 Jan 23, 2025

Choose a reason for hiding this comment

noliveleger left a comment

Choose a reason for hiding this comment

rajpatel24 commented Dec 20, 2024 •

edited

Loading

magicznyleszek commented Jan 4, 2025 •

edited

Loading